home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD 2.1 / Amiga Developer CD v2.1.iso / NDK / NDK_3.5 / Documentation / Autodocs / sound_dtc.doc < prev    next >
Encoding:
Text File  |  1999-10-30  |  11.5 KB  |  272 lines
  1. TABLE OF CONTENTS
  2.  
  3. sound.datatype/sound.datatype
  4. sound.datatype/sound.datatype                   sound.datatype/sound.datatype
  5.  
  6.     NAME
  7.         sound.datatype -- root data type for sounds.
  8.  
  9.     FUNCTION
  10.         The sound.datatype is the super-class for any sound related
  11.         classes.
  12.  
  13.     METHODS
  14.         OM_NEW -- Create a new sound object.
  15.  
  16.         OM_GET -- Obtain the value of an attribute.
  17.  
  18.         OM_SET -- Set the values of multiple attributes.
  19.  
  20.         OM_UPDATE -- Update the values of multiple attributes.
  21.  
  22.         OM_DISPOSE -- Dispose of a sound object.
  23.  
  24.         GM_LAYOUT -- Layout the object and notify the application of the
  25.             title and size.
  26.  
  27.         GM_HITTEST -- Determine if the object has been hit with the
  28.             mouse.
  29.  
  30.         GM_GOACTIVE -- Tell the object to go active.  On SELECTDOWN, the
  31.             sound will start playing.
  32.  
  33.         GM_HANDLEINPUT -- Handle input.  Currently input (other than
  34.             SELECTDOWN) doesn't affect the sound.
  35.  
  36.         GM_RENDER -- Cause the graphic to render.  Currently the graphic
  37.             for the sound is just a static icon.
  38.  
  39.         DTM_TRIGGER -- Cause an event to occur.  Currently the only
  40.             trigger event is STM_PLAY, which will cause the sound to start
  41.             playing.
  42.  
  43.             NOTE: Subclasses which support streaming data access may
  44.                   support more than just the STM_PLAY event.
  45.  
  46.         DTM_COPY -- Copy the entire sound to the clipboard as 8SVX.
  47.  
  48.             NOTE: Up to and including V40 sound.datatype never stored
  49.                   a valid VoiceHeader with the file. This was fixed in V44.
  50.  
  51.                   Subclasses which support streaming data access may not
  52.                   support this method.
  53.  
  54.         DTM_WRITE -- Write the entire sound to a file as 8SVX.
  55.  
  56.             NOTE: Up to and including V40 sound.datatype never stored
  57.                   a valid VoiceHeader with the file. This was fixed in V44.
  58.  
  59.                   Subclasses which support streaming data access may not
  60.                   support this method.
  61.  
  62.     TAGS
  63.         SDTA_VoiceHeader (struct VoiceHeader *) -- Set and get the base
  64.             information for the sound.  VoiceHeader is defined in
  65.             <datatypes/soundclass.h>.
  66.  
  67.             NOTE: Up to and including V40 sound.datatype never returned
  68.                   a valid VoiceHeader for OM_GET and the VoiceHeader data
  69.                   was ignored in the OM_NEW/OM_SET cases. This was fixed
  70.                   in V44.
  71.  
  72.             Applicability is (ISG).
  73.  
  74.         SDTA_Sample (BYTE *) -- Set and get the sound data.  Starting
  75.             with V40 the sample data does not need to be in CHIP memory.
  76.             Starting with V44 the sample data does not need to start
  77.             on a WORD-aligned address. Setting SDTA_Sample to NULL
  78.             will stop sound replay if sound.datatype was started
  79.             playing with a non-NULL SDTA_Sample parameter.
  80.  
  81.             The SDTA_Sample parameter selects mono playback on any
  82.             sound channel that is currently available.
  83.  
  84.             NOTE: For streaming sound playback, SDTA_LeftSample,
  85.                   SDTA_RightSample, and SDTA_Sample will all be
  86.                   NULL (V44).
  87.  
  88.             Applicability is (ISG).
  89.  
  90.         SDTA_SampleLength (ULONG) -- Length of the sound data in bytes.
  91.             Starting with V44 the sample data does not need to be
  92.             an even number of bytes. Setting SDTA_SampleLength to 0
  93.             will stop sound replay.
  94.  
  95.             Applicability is (ISG).
  96.  
  97.         SDTA_Period (UWORD) -- Set and get the period of the sound
  98.             (in timing intervals per sample). This attribute can be
  99.             used to affect a playing sound. Please note that the
  100.             Amiga audio hardware does not reliably support playback
  101.             periods shorter than 124; sound.datatype will limit the
  102.             period to valid intervals (V44).
  103.  
  104.             Default for this tag is 394.  Applicability is (ISG).
  105.  
  106.         SDTA_Volume (UWORD) -- Set and get the volume of the sound. This
  107.             attribute can be used to affect a playing sound.
  108.  
  109.             Valid range is from 0 to 64.  Default for this tag is 64.
  110.             Applicability is (ISG).
  111.  
  112.         SDTA_Cycles (UWORD) -- Set and get the number of cycles the
  113.             sound will be played.
  114.  
  115.             Default for this tag is 1.  Applicability is (ISG).
  116.  
  117.         The following tags are new for V40.
  118.  
  119.         SDTA_SignalTask (struct Task *) -- Task to signal when the
  120.             is complete, or if SDTA_Continuous is TRUE, when
  121.             the next buffer is needed.
  122.  
  123.             Default for this tag is NULL. Applicability is (IS).
  124.  
  125.         SDTA_SignalBit (ULONG) -- Signal mask to use with SDTA_SignalTask
  126.             or 0 to disable.
  127.  
  128.             NOTE: Due to a bug in sound.datatype V40 SDTA_SignalBit was
  129.                   actually implemented as a signal mask as opposed to a
  130.                   bit number. The documentation now reflects this. If you
  131.                   intend to use a signal bit number instead of the mask,
  132.                   use the new V44 tag SDTA_SignalBitNumber below.
  133.  
  134.             Default for this tag is 0. Applicability is (IS).
  135.  
  136.         SDTA_Continuous (BOOL) -- Used to indicate that the sound
  137.             datatype will be fed a continuous stream of data.
  138.  
  139.             Default for this tag is FALSE. Applicability is (I).
  140.  
  141.         The following tags are new for V44.
  142.  
  143.         SDTA_SignalBitMask (ULONG) -- Signal mask to use with SDTA_SignalTask
  144.             or 0 to disable. This tag is an alias for SDTA_SignalBit.
  145.  
  146.             Default for this tag is 0. Applicability is (IS).
  147.  
  148.         SDTA_SignalBitNumber (BYTE) -- Signal bit to use with SDTA_SignalTask
  149.             or -1 to disable.
  150.  
  151.             Default for this tag is -1. Applicability is (IS).
  152.  
  153.         SDTA_SamplesPerSec (UWORD) -- Set and get the replay frequency of
  154.             a sound (in Hz). This attribute can be used to affect a playing
  155.             sound. Unlike the SDTA_Period tag, which serves the same purpose,
  156.             this tag automatically takes the system clock value into account.
  157.             Please note that the Amiga audio hardware does not reliably
  158.             support playback rates beyond 28,000 samples per second;
  159.             sound.datatype will limit the replay frequency to valid
  160.             intervals.
  161.  
  162.             Applicability is (ISG).
  163.  
  164.         SDTA_ReplayPeriod (struct timeval *) -- Get the replay period,
  165.             i.e. the time it takes for the complete sound to be played.
  166.             If the sample size has not been set yet, the timeval tv_sec
  167.             and tv_micro members will be set to 0. If the sample is to
  168.             be played continuously, both timeval members will be set
  169.             to 0xFFFFFFFF.
  170.  
  171.             Applicability is (G).
  172.  
  173.         SDTA_Pan (BYTE) -- Set the stereo panning; this must be set to
  174.             a number in the range of -64..64. A value of -64 will
  175.             pan the sound to the left channel, silencing the right
  176.             channel; a value of 64 will pan the sound to the right
  177.             channel and silence the left channel. To center playback,
  178.             use a panning value of 0. The panning value only takes
  179.             effect if a stereo sound is being played.
  180.  
  181.             Default for this tag is 0. Applicability is (IS).
  182.  
  183.         SDTA_FreeSampleData (BOOL) -- This tag controls whether
  184.             sound.datatype will call FreeVec() on the sample data
  185.             attached to an object. If the SDTA_Continuous attribute was
  186.             set to TRUE, sound.datatype will never free any data attached
  187.             to an object. It is safe to attach the same sample to
  188.             more than one channel as sound.datatype will make sure that
  189.             no sample data is freed twice.
  190.  
  191.             Default for this tag is FALSE. Applicability is (IS).
  192.  
  193.         SDTA_LeftSample (BYTE *) -- Set and get the left channel sound data.
  194.             The sample data does not need to be in CHIP memory and does
  195.             not need to start on a WORD-aligned address. Setting
  196.             SDTA_LeftSample to NULL will stop sound replay if sound.datatype
  197.             was started playing with a non-NULL SDTA_LeftSample parameter.
  198.  
  199.             The SDTA_LeftSample parameter alone selects mono playback on
  200.             any left sound channel that is currently available. Used together
  201.             with the SDTA_RightSample parameter, stereo playback on any
  202.             available stereo channels is selected.
  203.  
  204.             The SDTA_LeftSample parameter takes precedence over the
  205.             the SDTA_Sample parameter.
  206.  
  207.             NOTE: For streaming sound playback, SDTA_LeftSample,
  208.                   SDTA_RightSample, and SDTA_Sample will all be
  209.                   NULL (V44).
  210.  
  211.             Applicability is (ISG).
  212.  
  213.         SDTA_RightSample (BYTE *) -- Set and get the right channel sound data
  214. .
  215.             The sample data does not need to be in CHIP memory and does
  216.             not need to start on a WORD-aligned address. Setting
  217.             SDTA_RightSample to NULL will stop sound replay if sound.datatype
  218.             was started playing with a non-NULL SDTA_RightSample parameter.
  219.  
  220.             The SDTA_RightSample parameter alone selects mono playback on
  221.             any right sound channel that is currently available. Used
  222.             together with the SDTA_LeftSample parameter, stereo playback
  223.             on any available stereo channels is selected.
  224.  
  225.             The SDTA_RightSample parameter takes precedence over the
  226.             the SDTA_Sample parameter.
  227.  
  228.             NOTE: For streaming sound playback, SDTA_LeftSample,
  229.                   SDTA_RightSample, and SDTA_Sample will all be
  230.                   NULL (V44).
  231.  
  232.             Applicability is (ISG).
  233.  
  234.         SDTA_SyncSampleChange (BOOL) -- If SDTA_Continuous was set to TRUE,
  235.             sound.datatype will expect a continuous stream of data to be
  236.             played. By specifying "SDTA_SyncSampleChange,TRUE" you request
  237.             that new sound data will be played only if the old data has
  238.             been played completely (otherwise, playback would restart
  239.             immediately with the new sound). If playback is currently in
  240.             progress, the Task to change the sample data will be made to
  241.             wait until playback of the old sound has finished.
  242.  
  243.             Default for this tag is FALSE. Applicability is (IS).
  244.  
  245.         DTA_Immediate (BOOL) -- Select and query whether playback should
  246.             start immediately after the object has passed the layout
  247.             process.
  248.  
  249.             Default for this tag is FALSE. Applicability is (ISG).
  250.  
  251.         DTA_Repeat (BOOL) -- Select and query whether playback should
  252.             loop indefinitely, regardless of the current SDTA_Cycles
  253.             settings.
  254.  
  255.             Default for this tag is FALSE. Applicability is (ISG).
  256.  
  257.     NOTES
  258.         You cannot switch between mono and stereo playback on the fly while
  259.         the sound is still playing. First, stop the sound, then change the
  260.         SDTA_Sample/SDTA_LeftSample/SDTA_LeftSample attributes.
  261.  
  262.         The sound.datatype implementation has been cleaned up for V44 to
  263.         allow for streaming subclasses to be written. Such subclasses will
  264.         always return NULL when their SDTA_LeftSample, SDTA_RightSample and
  265.         SDTA_Sample attributes are queried. However, they will never return
  266.         0 for the SDTA_SampleLength and SDTA_SamplesPerSec attributes since
  267.         these can be used to calculate the length of the entire sample.
  268.         Streaming subclasses will respond to the DTM_TRIGGER method, to
  269.         start, stop playback, etc. but may not support any other methods
  270.         which rely upon the entire sample to reside in memory.
  271.  
  272.